return

Type

control structure

Summary

Stops the current handler and returns a value to the handler that called the current handler.

Syntax

return <value> [ for { value | error } ]

Description

Use the return control structure to return a value from a custom function or getProp handler, or to return an error message from a message handler or setProp handler.

Form: The return statement appears on a line by itself, anywhere inside a handler.

When the return control structure is executed, any remaining statements in the handler are skipped. Hence, the return control structure is usually used either at the end of a handler or within an if control structure.

The plain form of the return control structure always sets the result to value. Additionally, if it is used within a function or getProp handler then value is passed to the calling handler as the return value of the function, or value of the property.

The value form of the return control structure always sets the result to empty. If it is used within a command or message handler then the it variable in the calling handler will be set to value. If it is used within a function handler, then value is passed to the calling handler as the return value of the function, or value of the property.

The error form of the return control structure sets the result to value. If it is used within a command or message handler, then the it variable in the calling handler will be set to empty. If it is used within a function handler, then the return value of the function or the value of the property is returned as empty.

Note: The value and error forms can only be used within message, command and function handlers - not getProp or setProp handlers.

When a message handler executes a return statement, the message stops and is not passed to the next object in the message path. To halt the current message handler and pass the message on through the message path, use the pass control structure instead. To halt the current handler without returning a value, use the exit control structure instead.

The value and error forms of the return command allow much easier scripting of the distinction between a return value of a handler call, and an error return value of a handler call. If a command or function handler succeeds, then the 'return for value' form should be used to return the result of the execution to the calling handler. If a command or function handler fails, then the 'return for error' form should be used to return an error status to the calling handler.

Any callers of handlers using the new error and value forms of the return command can uniformly check the result is empty to determine if the operation succeeded, and if it did then either it or the return value can be processed to continue operation.

note

The return control structure is implemented internally as a command and appears in the commandNames.

Parameters

Name	Type	Description
value		The value to return to the calling handler.

Examples

    function simpleFunction
       return 1
    end simpleFunction
    on testSimpleFunction
       local tVar
       put simpleFunction() into tVar
       -- tVar contains 1, the result contains 1
    end testSimpleFunction

    function simpleFunction
       return 1 for value
    end simpleFunction
    on testSimpleFunction
       local tVar
       put simpleFunction() into tVar
       -- tVar contains 1, the result contains empty
    end testSimpleFunction

    function simpleFunction
       return 1 for error
    end simpleFunction
    on testSimpleFunction
       local tVar
       put simpleFunction() into tVar
       -- tVar contains empty, the result contains 1
    end testSimpleFunction

    command simpleCommand
       return 1
    end simpleCommand
    on testSimpleCommand
       simpleCommand
       -- the result contains 1
    end testSimpleCommand

    command simpleCommand
       return 1 for value
    end simpleCommand
    on testSimpleCommand
       simpleCommand
       -- it contains 1, the result contains empty
    end testSimpleCommand

    command simpleCommand
       return 1 for error
    end simpleCommand
    on testSimpleCommand
       simpleCommand
       -- it contains empty, the result contains 1
    end testSimpleCommand

Related

control structure: setProp, getProp, throw, if, pass, exit, on, function

function: result, commandNames, value, merge

glossary: object, message handler, call, property, pass, execute, command, control structure, message path, caller, message, statement, handler, return

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile